/*
 *  Copyright (C) 2010 Glauco
 * 
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 * 
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 * 
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package org.balisunrise.builder;

import java.util.List;
import org.balisunrise.annotation.util.ActionUtilities;
import org.balisunrise.common.Action;
import org.balisunrise.common.FieldAction;
import org.balisunrise.common.VisualAction;
import org.balisunrise.common.TransactionActions;

/**
 * Esta Inteface é resposável pela construção de ações para mapas de ações de
 * entidades.
 *
 * @author Glauco
 * @see org.balisunrise.annotation.Action
 * @see org.balisunrise.annotation.VisualAction
 * @see org.balisunrise.common.Action
 * @see org.balisunrise.common.VisualAction
 */
public interface ActionBuilder {

    /**
     * Cria uma ação com as propriedade do ActionUtilities.
     * @param au  Utilitário com espeficicações para criação da ação.
     * @return uma instância de Action.
     * @throws BuilderException caso algum parametro seja nulo.
     */
    public Action createAction(ActionUtilities au)
            throws BuilderException;

    /**
     * Cria uma ação para instância do mapa de ações a partir do alias
     * declarado.<br><br>
     * Este método é util para criar ações em tempo de execução e adiciná-las
     * nos locais desejados.
     *
     * @param actionMap Instância do mapa de ações.
     * @param alias Alias para construção da ação.
     * @return Lista de ações encontradas para o mapa de ações de alias.
     * @throws BuilderException Caso algum parametro seja nulo.
     */
    public List<Action> createAction(Object actionMap, String alias)
            throws BuilderException;

    /**
     * Cria uma ação visual com as propriedade do ActionUtilities.
     *
     * @param au Utilitário com espeficicações para criação da ação visual.
     * @return uma instância de VisualAction.
     * @throws BuilderException caso algum parametro seja nulo.
     */
    public VisualAction createVisualAction(ActionUtilities au)
            throws BuilderException;

    /**
     * Cria uma ação visual para instância do mapa de ações a partir do alias
     * declarado.<br><br>
     * Este método é util para criar ações em tempo de execução e adiciná-las
     * nos locais desejados.
     * 
     * @param actionMap Instância do mapa de ações.
     * @param alias Alias para construção da ação.
     * @return Lista de ações visuais encontradas para o mapa de ações de alias.
     * @throws BuilderException Caso algum parametro seja nulo.
     */
    public List<VisualAction> createVisualAction(Object actionMap, String alias)
            throws BuilderException;
    /**
     * Cria a ação de confirmação.
     *
     * @param actionMap Objeto que possui o método da ação.
     * @param alias alias da ação de confirmação.
     * @return um objeto de VisualAction, ou nulo se não existir.
     * @throws BuilderException caso algum parametro seja nulo.
     */
    public VisualAction createConfirmationAction(Object actionMap, String alias)
            throws BuilderException;

    /**
     * Cria a ação de cancelamento.
     *
     * @param actionMap Objeto que possui o método da ação.
     * @param alias alias da ação de cancelamento.
     * @return um objeto de VisualAction, ou nulo se não existir.
     * @throws BuilderException caso algum parametro seja nulo.
     */
    public VisualAction createCancellationAction(Object actionMap, String alias)
            throws BuilderException;

    /**
     * Cria as Ações Search, New, Edit, Delete de uma TransactionAction.<br>
     * As ações são retornadas conforme a sequencia descrita acima.
     *
     * @param actionMap TransactionActions de uma transação.
     * @return Uma lista com as quatro (4) Ações da TransactionActions.
     * @throws BuilderException caso algum parametro seja nulo.
     */
    public List<VisualAction> createTransactionAction(TransactionActions actionMap)
            throws BuilderException;

    /**
     * Cria a ação visual de um campo a apartir dos dados do ActionUtilities.
     * @param au ActionUtilities para criar a ação visual de campo.
     * @return Uma nova instância de FieldAction.
     * @throws BuilderException caso algum parametro seja nulo.
     */
    public FieldAction createFieldAction(ActionUtilities au)
            throws BuilderException;
}
